Почта Росcии

Спецификация
- Единичный доступ
- Пакетный доступ

Помощь

Единичный доступ

Режим Единичного доступа позволяет за одно обращение к Сервису отслеживания получить информацию по одному регистрируемому почтовому отправлению (РПО). Возможны следующие запросы:

получение подробной информации обо всех операциях, совершенных над отправлением (метод getOperationHistory). Информация об одной операции включает время и место проведения операции, код и атрибут операции, название операции и другие поля;
получение информации об операциях с наложенным платежом, который связан с отправлением (метод PostalOrderEventsForMail).

Протокол Единичного доступа реализован на основе SOAP (Simple Object Access Protocol).

1. Основная информация по использованию API

Адрес сервиса	https://tracking.russianpost.ru/rtm34
WSDL	https://tracking.russianpost.ru/rtm34?wsdl
Методы	getOperationHistory возвращает историю операций над отправлением PostalOrderEventsForMail возвращает историю операций с наложенным платежом
Базовый протокол	SOAP 1.2
Параметры доступа	могут быть получены в разделе Настройки доступа зарегистрированного пользователя, у которого подключен доступ к API
Примеры кода	Примеры кода для работы с API

2. Метод getOperationHistory

Метод getOperationHistory используется для получения информации о конкретном отправлении. Метод возвращает подробную информацию по всем операциям, совершенным над отправлением.

2.1. Запрос

Элемент		Описание	Обязательность
OperationHistoryRequest		Содержит элементы Barcode, MessageType, Language.
	Barcode	Идентификатор регистрируемого почтового отправления в одном из форматов: - внутрироссийский, состоящий из 14 символов (цифровой); - международный, состоящий из 13 символов (буквенно-цифровой) в формате S10.	Да
	MessageType	Тип сообщения. Возможные значения: 0 - история операций для отправления; 1 - история операций для заказного уведомления по данному отправлению.	Да
	Language	Язык, на котором должны возвращаться названия операций/атрибутов и сообщения об ошибках. Допустимые значения: RUS – использовать русский язык (используется по умолчанию); ENG – использовать английский язык.	Нет
AuthorizationHeader		Содержит элементы login и password. Атрибут soapenv:mustUnderstand элемента AuthorizationHeader должен содержать значение 1.
	login	Логин для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.	Да
	password	Пароль для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.	Да

2.2. Ответ

Ответ метода getOperationHistory содержит список элементов historyRecord. Каждый из них содержит информацию об одной операции над отправлением. Если над отправлением еще не зарегистрировано ни одной операции, то возвращается пустой список элементов historyRecord.

По каждой операции в ответе обязательно присутствует следующая информация:
- Дата операции (OperDate);
- Место проведения операции (OperationAddress);
- Операция (OperType) и ее атрибут (OperAttr).

Прочая информация возвращается при её наличии в Сервисе отслеживания.

Элемент				Описание
AddressParameters				Содержит адресные данные с операцией над отправлением.
		DestinationAddress		Содержит адресные данные места назначения пересылки отправления.
			Index	Почтовый индекс места назначения. Не возвращается для зарубежных операций.
			Description	Адрес и/или название места назначения. Пример значения.
		OperationAddress		Содержит адресные данные места проведения операции над отправлением.
			Index	Почтовый индекс места проведения операции. Не возвращается для зарубежных операций.
			Description	Адрес и/или название места проведения операции.
		MailDirect		Содержит данные о стране места назначения пересылки отправления.
			Id	Код страны. Возможные коды приведены в поле "Код" справочника стран.
			Code2A	Двухбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.
			Code3A	Трехбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha3 код" справочника стран.
			NameRu	Российское название страны. Возможные названия приведены в поле "Наименование страны пересылки" справочника стран.
			NameEN	Международное название страны. Возможные названия приведены в поле «Английское наименование страны пересылки» справочника стран.
		CountryFrom		Содержит данные о стране приема почтового отправления.
			Id	Код страны. Возможные коды приведены в поле "Код" справочника стран.
			Code2A	Двухбуквенный идентификатор страны. Двухбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.
			Code3A	Трехбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha3 код" справочника стран.
			NameRu	Российское название страны. Возможные названия приведены в поле "Наименование страны пересылки" справочника стран.
			NameEN	Международное название страны. Возможные названия приведены в поле «Английское наименование страны пересылки» справочника стран.
		CountryOper		Содержит данные о стране проведения операции над почтовым отправлением.
			Id	Код страны. Возможные коды приведены в поле "Код" справочника стран.
			Code2A	Двухбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.
			Code3A	Трехбуквенный идентификатор страны. Возможные идентификаторы приведены в поле "Alpha3 код" справочника стран.
			NameRu	Российское название страны. Возможные названия приведены в поле "Наименование страны пересылки" справочника стран.
			NameEN	Международное название страны. Возможные названия приведены в поле «Английское наименование страны пересылки» справочника стран.
FinanceParameters				Содержит финансовые данные, связанные с операцией над почтовым отправлением.
	Payment			Сумма наложенного платежа в копейках.
	Value			Сумма объявленной ценности в копейках.
	MassRate			Общая сумма платы за пересылку наземным и воздушным транспортом в копейках.
	InsrRate			Сумма платы за объявленную ценность в копейках.
	AirRate			Выделенная сумма платы за пересылку воздушным транспортом из общей суммы платы за пересылку в копейках.
	Rate			Сумма дополнительного тарифного сбора в копейках.
	CustomDuty			Сумма таможенного платежа в копейках.
ItemParameters				Содержит данные о почтовом отправлении.
	Barcode			Идентификатор почтового отправления, текущий для данной операции.
	Internum			Служебная информация, идентифицирующая отправление, может иметь значение ДМ квитанции, связанной с отправлением или иметь значение <null>
	ValidRuType			Признак корректности вида и категории отправления для внутренней пересылки
	ValidEnType			Признак корректности вида и категории отправления для международной пересылки
	ComplexItemName			Содержит текстовое описание вида и категории отправления.
	MailRank			Содержит информацию о разряде почтового отправления.
			Id	Код разряда почтового отправления.
			Name	Название разряда почтового отправления.
	PostMark			Содержит информацию об отметках почтовых отправлений.
			Id	Код отметки почтового отправления.
			Name	Наименование отметки почтового отправления.
	MailType			Содержит данные о виде почтового отправления.
			Id	Код вида почтового отправления.
			Name	Название вида почтового отправления.
	MailCtg			Содержит данные о категории почтового отправления.
			Id	Код категории почтового отправления.
			Name	Название категории почтового отправления.
	Mass			Вес отправления в граммах.
	MaxMassRu			Значение максимально возможного веса для данного вида и категории отправления для внутренней пересылки.
	MaxMassEn			Значение максимально возможного веса для данного вида и категории отправления для международной пересылки.
OperationParameters				Cодержит параметры операции над отправлением
	OperType			Содержит информацию об операции над отправлением.
			Id	Код операции.
			Name	Название операции.
	OperAttr			Содержит информацию об атрибуте операции над отправлением.
			Id	Код атрибута.
			Name	Название атрибута.
	OperDate			Содержит данные о дате и времени проведения операции над отправлением. Пример значения: 2015-01-08T14:50:00.000+03:00
UserParameters				Содержит данные субъектов, связанных с операцией над почтовым отправлением.
	SendCtg			Содержит информацию о категории отправителя.
			Id	Идентификатор категории отправителя.
			Name	Название категории отправителя.
	Sndr			Содержит данные об отправителе. Пример значения: ИВАНОВ А Н
	Rcpn			Содержит данные о получателе отправления. Пример значения: ПЕТРОВ И.К.

2.3. Возможные ошибки

Вид ошибки	Описание
Ошибка авторизации	При обращении к Сервису отслеживания произошла ошибка авторизации. Элемент AuthorizationFault cодержит подробное описание ошибки.
Ошибка получения информации об отправлении	При попытке получить информацию об отправлении произошла ошибка. Элемент OperationHistoryFault cодержит подробное описание ошибки.
Заданный язык не поддерживается	В запросе был указан недопустимый идентификатор языка. Элемент LanguageFault cодержит подробное описание ошибки.

Вид ошибки

Описание

Ошибка авторизации

При обращении к Сервису отслеживания произошла ошибка авторизации.

Элемент AuthorizationFault cодержит подробное описание ошибки.

Ошибка получения информации об отправлении

При попытке получить информацию об отправлении произошла ошибка.

Элемент OperationHistoryFault cодержит подробное описание ошибки.

Заданный язык не поддерживается

В запросе был указан недопустимый идентификатор языка.

Элемент LanguageFault cодержит подробное описание ошибки.

2.4. Пример запроса и ответа

Пример запроса:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:oper="http://russianpost.org/operationhistory" xmlns:data="http://russianpost.org/operationhistory/data" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Header/>
<soap:Body>
<oper:getOperationHistory>
<data:OperationHistoryRequest>
<data:Barcode>RA644000001RU</data:Barcode>
<data:MessageType>0</data:MessageType>
<data:Language>RUS</data:Language>
</data:OperationHistoryRequest>
<data:AuthorizationHeader soapenv:mustUnderstand="1">
<data:login>my_login</data:login>
<data:password>my_password</data:password>
</data:AuthorizationHeader>
</oper:getOperationHistory>
</soap:Body>
</soap:Envelope>

Пример ответа:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
<ns7:getOperationHistoryResponse xmlns:ns2="http://russianpost.org/sms-info/data" xmlns:ns3="http://russianpost.org/operationhistory/data" xmlns:ns4="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns5="http://www.russianpost.org/custom-duty-info/data" xmlns:ns6="http://www.russianpost.org/RTM/DataExchangeESPP/Data" xmlns:ns7="http://russianpost.org/operationhistory">
<ns3:OperationHistoryData>
<ns3:historyRecord>
<ns3:AddressParameters>
<ns3:DestinationAddress>
<ns3:Index>663300</ns3:Index>
<ns3:Description>Норильск Почтамт</ns3:Description>
</ns3:DestinationAddress>
<ns3:OperationAddress>
<ns3:Index>111555</ns3:Index>
<ns3:Description>Москва 555</ns3:Description>
</ns3:OperationAddress>
<ns3:MailDirect>
<ns3:Id>643</ns3:Id>
<ns3:Code2A>RU</ns3:Code2A>
<ns3:Code3A>RUS</ns3:Code3A>
<ns3:NameRU>Российская Федерация</ns3:NameRU>
<ns3:NameEN>Russian Federation</ns3:NameEN>
</ns3:MailDirect>
<ns3:CountryOper>
<ns3:Id>643</ns3:Id>
<ns3:Code2A>RU</ns3:Code2A>
<ns3:Code3A>RUS</ns3:Code3A>
<ns3:NameRU>Российская Федерация</ns3:NameRU>
<ns3:NameEN>Russian Federation</ns3:NameEN>
</ns3:CountryOper>
</ns3:AddressParameters>
<ns3:FinanceParameters>
<ns3:Payment>2500000</ns3:Payment>
<ns3:Value>2500000</ns3:Value>
<ns3:MassRate>152000</ns3:MassRate>
<ns3:InsrRate>25000</ns3:InsrRate>
<ns3:AirRate>0</ns3:AirRate>
<ns3:Rate>0</ns3:Rate>
</ns3:FinanceParameters>
<ns3:ItemParameters>
<ns3:Barcode>EA123456789RU</ns3:Barcode>
<ns3:ValidRuType>true</ns3:ValidRuType>
<ns3:ValidEnType>false</ns3:ValidEnType>
<ns3:PostMark>
<ns3:Id>0</ns3:Id>
<ns3:Name>Без отметки</ns3:Name>
<ns3:MailRank>
<ns3:Id>0</ns3:Id>
<ns3:Name>Без разряда</ns3:Name>
</ns3:MailRank>
<ns3:PostMark>
<ns3:Id>0</ns3:Id>
<ns3:Name>Без отметки</ns3:Name>
</ns3:PostMark>
<ns3:MailType>
<ns3:Id>7</ns3:Id>
<ns3:Name>Отправление EMS</ns3:Name>
</ns3:MailType>
<ns3:MailCtg>
<ns3:Id>4</ns3:Id>
<ns3:Name>С объявленной ценностью и наложенным платежом</ns3:Name>
</ns3:MailCtg>
<ns3:Mass>2281</ns3:Mass>
</ns3:ItemParameters>
<ns3:OperationParameters>
<ns3:OperType>
<ns3:Id>1</ns3:Id>
<ns3:Name>Прием</ns3:Name>
</ns3:OperType>
<ns3:OperAttr>
<ns3:Id>1</ns3:Id>
<ns3:Name>Единичный</ns3:Name>
</ns3:OperAttr>
<ns3:OperDate>2015-07-09T18:08:00.000+03:00</ns3:OperDate>
</ns3:OperationParameters>
<ns3:UserParameters>
<ns3:SendCtg>
<ns3:Id>1</ns3:Id>
<ns3:Name>Население</ns3:Name>
</ns3:SendCtg>
<ns3:Sndr>ИВАНОВ И Н</ns3:Sndr>
<ns3:Rcpn>ПЕТРОВ Н И</ns3:Rcpn>
</ns3:UserParameters>
</ns3:historyRecord>
<ns3:historyRecord>
…
</ns3:historyRecord>
…
</ns3:OperationHistoryData>
</ns7:getOperationHistoryResponse>
</S:Body>
</S:Envelope>

3. Метод PostalOrderEventsForMail

Метод PostalOrderEventsForMail позволяет получить информацию об операциях с наложенным платежом, который связан с конкретным почтовым отправлением.

3.1. Запрос

Элемент		Атрибут	Описание	Обязательность
AuthorizationHeader			Содержит элементы login и password. Атрибут soapenv:mustUnderstand элемента AuthorizationHeader должен содержать значение 1.
	login		Логин для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.	Да
	password		Пароль для доступа к API Сервиса отслеживания. Может быть получен в разделе Настройки доступа.	Да
PostalOrderEventsForMailInput			Содержит атрибуты Barcode, и Language.	Да
		Barcode	Идентификатор РПО в одном из форматов: - внутрироссийский, состоящий из 14 символов (цифровой); - международный, состоящий из 13 символов (буквенно-цифровой) в формате S10.
		Language	Язык, используемый в ответных сообщениях. Возможные значения: RUS – русский (используется по умолчанию) ENG – английский

3.2. Ответ

Элемент	Атрибут	Описание
PostalOrderEvent	Number	Номер почтового перевода наложенного платежа.
	EventDateTime	Дата и время операции в формате YYYY-MM-DDTHH:mm:ss.SSSZ Пример значения: 2015-12-11T15:04:37.000+03:00
	EventType	Код операции с наложенным платежом
	EventName	Название операции
	IndexTo	Почтовый индекс получателя
	IndexEvent	Почтовый индекс отделения почтовой связи, в котором была совершена операция
	SumPaymentForward	Сумма наложенного платежа в копейках
	CountryEventCode	Двухбуквенный идентификатор страны, в которой была совершена операция. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.
	CountryToCode	Двухбуквенный идентификатор страны получателя наложенного платежа. Возможные идентификаторы приведены в поле "Alpha2 код" справочника стран.

3.3. Возможные ошибки

Вид ошибки	Описание
Ошибка авторизации	При обращении к Сервису отслеживания произошла ошибка авторизации.

Вид ошибки

Описание

Ошибка авторизации

При обращении к Сервису отслеживания произошла ошибка авторизации.

3.4. Пример запроса и ответа

Пример запроса:

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:oper="http://russianpost.org/operationhistory" xmlns:data="http://russianpost.org/operationhistory/data" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:data1="http://www.russianpost.org/RTM/DataExchangeESPP/Data">
<soap:Header/>
<soap:Body>
   <oper:PostalOrderEventsForMail>
      <data:AuthorizationHeader soapenv:mustUnderstand="1">
         <data:login>my_login</data:login>
         <data:password>my_password</data:password>
      </data:AuthorizationHeader>
      <data1:PostalOrderEventsForMailInput Barcode="14102192069353" Language="ENG"/>
   </oper:PostalOrderEventsForMail>
</soap:Body>
</soap:Envelope>

Пример ответа:

<S:Envelope xmlns:S="http://www.w3.org/2003/05/soap-envelope">
<S:Body>
   <ns7:PostalOrderEventsForMailResponse xmlns:ns2="http://russianpost.org/sms-info/data" xmlns:ns3="http://russianpost.org/operationhistory/data" xmlns:ns4="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ns5="http://www.russianpost.org/custom-duty-info/data" xmlns:ns6="http://www.russianpost.org/RTM/DataExchangeESPP/Data" xmlns:ns7="http://russianpost.org/operationhistory">
      <ns6:PostalOrderEventsForMaiOutput>
         <PostalOrderEvent Number="96598" EventDateTime="2015-12-11T15:04:37.000+03:00" EventType="1" EventName="Приём" IndexTo="141021" IndexEvent="298300" SumPaymentForward="234000" CountryEventCode="RU" CountryToCode="RU"/>
         <PostalOrderEvent Number="96598" EventDateTime="2015-12-12T16:49:13.000+03:00" EventType="3" EventName="Оплата" IndexTo="141021" IndexEvent="141021" SumPaymentForward="234000" CountryEventCode="RU" CountryToCode="RU"/>
      </ns6:PostalOrderEventsForMaiOutput>
   </ns7:PostalOrderEventsForMailResponse>
</S:Body>
</S:Envelope>